SPI Master Peripheral Driver

The section describes the programming interface of the SPI master mode Peripheral driver. More...

Data Structures
struct	spi_user_config_t
	Information about a device on the SPI bus. More...

Enumerations
enum	_spi_timeouts { kSpiWaitForever = 0xffffffffU }

Initialization and shutdown
void	spi_master_init (uint32_t instance)
	Initializes an SPI instance for master mode operation. More...
void	spi_master_shutdown (uint32_t instance)
	Shuts down an SPI instance. More...

Bus configuration
void	spi_master_configure_bus (uint32_t instance, const spi_user_config_t *device)
	Configures the SPI port to access a device on the bus. More...

Blocking transfers
spi_status_t	spi_master_transfer (uint32_t instance, const spi_user_config_t *restrict device, const uint8_t *restrict sendBuffer, uint8_t *restrict receiveBuffer, size_t transferByteCount, uint32_t timeout)
	Performs a blocking SPI master mode transfer. More...

Non-blocking transfers
spi_status_t	spi_master_transfer_async (uint32_t instance, const spi_user_config_t *restrict device, const uint8_t *restrict sendBuffer, uint8_t *restrict receiveBuffer, size_t transferByteCount)
	Performs a non-blocking SPI master mode transfer. More...
spi_status_t	spi_master_get_tranfer_status (uint32_t instance, uint32_t *bytesTransferred)
	Returns whether the previous transfer finished. More...
spi_status_t	spi_master_abort_transfer (uint32_t instance)
	Terminates an asynchronous transfer early. More...

SPI Master Peripheral Driver

Overview

The SPI master mode peripheral driver transfers data to and from the external devices on the SPI bus in master mode. It provides an easy way to transfer buffers of data with a single function call.

Device structures

The driver uses instances of the #spi_device_t structure to represent the SPI bus configuration required to communicate the bus connectivity to an external device.The device structures can be passed to the data transfer functions and the bus is reconfigured before the transfer is started. Alternatively, you can manually configure the SPI bus for a device. For example, if there is only one device connected to the bus, you might configure it only once.

Initialization

To initialize the SPI master driver, call the spi_master_init() function and pass the instance number of the SPI peripheral you want to use. For example, to use the SPI1, pass a value of 1 to the initialization function.This is an example code to initialize and configure the driver:

// Define bus configuration.
spi_device_t device = {
        .busFrequencyKHz = 1000,
        .polarity = kSpiClockPolarity_ActiveHigh,
        .phase = kSpiClockPhase_SecondEdge,
        .direction = kSpiMsbFirst
    };

// Init driver.
spi_master_init(0);

// Configure bus.
spi_master_configure_bus(0, &device);

Transfers

The driver supports two different modes to transfer data: blocking and non-blocking. The blocking transfer function is the spi_master_transfer().This is an example of a blocking transfer:

uint8_t sendBuf[] = { 0, 1, 2, 3 };
uint8_t receiveBuf[sizeof(sendBuf)];

spi_master_transfer(0,  // SPI0
    &device,            // Device SPI bus configuration
    sendBuf,            // Data to send
    receiveBuf,         // Buffer to hold received data
    sizeof(sendBuf),    // Number of bytes to transfer
    kSpiWaitForever);   // No timeout

This is an example of a non-blocking transfer:

uint8_t sendBuf[] = { 0, 1, 2, 3 };
uint8_t receiveBuf[sizeof(sendBuf)];

// Start the transfer.
spi_master_transfer_async(0,  // SPI0
    &device,            // Device SPI bus configuration
    sendBuf,            // Data to send
    receiveBuf,         // Buffer to hold received data
    sizeof(sendBuf));   // Number of bytes to transfer

// Wait for the transfer to complete.
while (spi_master_get_transfer_status(0, NULL) == kStatus_SPI_Busy)
{
}

---

Data Structure Documentation

struct spi_user_config_t

Data Fields
uint32_t	busFrequencyKHz
spi_clock_polarity_t	polarity
spi_clock_phase_t	phase
spi_shift_direction_t	direction

Enumeration Type Documentation

enum _spi_timeouts

Enumerator
kSpiWaitForever	Waits forever for a transfer to complete.

Function Documentation

void spi_master_init

(

uint32_t

instance

)

Parameters

instance

The instance number of the SPI peripheral.

void spi_master_shutdown

(

uint32_t

instance

)

Resets the SPI peripheral and gates its clock.

Parameters

instance

The instance number of the SPI peripheral.

void spi_master_configure_bus	(	uint32_t	instance,
		const spi_user_config_t *	device
	)

Parameters

instance	The instance number of the SPI peripheral.
device	Pointer to the device information structure. This structure contains the settings for SPI bus configurations.

spi_status_t spi_master_transfer	(	uint32_t	instance,
		const spi_user_config_t *restrict	device,
		const uint8_t *restrict	sendBuffer,
		uint8_t *restrict	receiveBuffer,
		size_t	transferByteCount,
		uint32_t	timeout
	)

This function simultaneously sends and receives data on the SPI bus, as SPI is naturally a full-duplex bus.

Parameters

instance	The instance number of the SPI peripheral.
device	Pointer to the device information structure. This structure contains the settings for the SPI bus configuration for this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified.
sendBuffer	Buffer of data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent.
receiveBuffer	Buffer where received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored.
transferByteCount	The number of bytes to send and receive.
timeout	A timeout for the transfer in microseconds. If the transfer takes longer than this amount of time, the transfer is aborted and a kStatus_SPI_Timeout error is returned.

Return values

#kStatus_Success	The transfer was successful.
kStatus_SPI_Busy	Cannot perform another transfer because one is already in progress.
kStatus_SPI_Timeout	The transfer timed out and was aborted.

spi_status_t spi_master_transfer_async	(	uint32_t	instance,
		const spi_user_config_t *restrict	device,
		const uint8_t *restrict	sendBuffer,
		uint8_t *restrict	receiveBuffer,
		size_t	transferByteCount
	)

Parameters

instance	The instance number of the SPI peripheral.
device	Pointer to the device information structure. This structure contains the settings for the SPI bus configuration for this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified.
sendBuffer	Buffer of data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) will be sent.
receiveBuffer	Buffer where received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored.
transferByteCount	The number of bytes to send and receive.

Return values

#kStatus_Success	The transfer was successful.
kStatus_SPI_Busy	Cannot perform another transfer because one is already in progress.
kStatus_SPI_Timeout	The transfer timed out and was aborted.

spi_status_t spi_master_get_tranfer_status	(	uint32_t	instance,
		uint32_t *	bytesTransferred
	)

Parameters

instance	The instance number of the SPI peripheral.
bytesTransferred	Pointer to a value that is filled in with the number of bytes that were sent in the active transfer

Return values

kStatus_Success	The transfer has completed successfully.
kStatus_SPI_Busy	The transfer is still in progress. bytesTransferred is filled with the number of bytes that have been transferred so far.

spi_status_t spi_master_abort_transfer

(

uint32_t

instance

)

Parameters

instance

The instance number of the SPI peripheral.

Return values

#kStatus_Success

The transfer was successful.